home *** CD-ROM | disk | FTP | other *** search
/ NeXT Education Software Sampler 1992 Fall / NeXT Education Software Sampler 1992 Fall.iso / Programming / Classes / serialComm / SerialCommDevice.h < prev    next >
Encoding:
C/C++ Source or Header  |  1992-08-03  |  6.4 KB  |  230 lines
  1. /*    SerialCommDevice.h
  2.  
  3.     This class defines an easy to use, robust, fault-tollerant, full-duplex serial 
  4.     communications protocol.  The implementation uses a packet-based protocol that 
  5.     transmits only printable ascii characters. 
  6.  
  7.     Automatic retries insure that this protocol doesn't fall flat on it's 
  8.     face whenever a packet fails to be successfully received. There is both 
  9.     a recieve timeout, and a transmit timeout.  The transmit timeout limits 
  10.     the length of time that the sender will wait for an ack to a data packet
  11.     transfer, while the recieve timeout limits the amount of time that a 
  12.     read waits for a valid data packet to be received. The default setting 
  13.     for recvTimeoutMsecs is 0 (not timeout) and xmitAckTimeoutMsecs is 250 
  14.     (1/4 sec).
  15.  
  16.     If a xmit timeout occures the data packet is re-sent to the remote 
  17.     interface. If a received packet has a bad checksum, then a NACK (negative
  18.     acknowledge) packet is immediatly transmitted. Failing xmit transfers 
  19.     (either due to timeout or receipt of NACK packet, will be automatically 
  20.     retried until the maxXmitRetries have been attempted.  The default setting 
  21.     for maxXmitRetries is 60, making 15 seconds the longest amount of time a 
  22.     transfer will be attempted for a broken network. Both timeouts and retries 
  23.     can be easily modified with the provided methods.
  24.  */
  25.  
  26. #import <objc/Object.h>
  27. #import <sys/time.h>
  28.  
  29. typedef enum {
  30.     noPort,
  31.     sccPortA,
  32.     sccPortB
  33. } sccPortType;
  34. extern char *portString(sccPortType thePort);     /* returns name of the specified port. */
  35.  
  36. typedef enum {
  37.     brNone=0, 
  38.     br50=1,
  39.     br75=2,
  40.     br110=3,
  41.     br134=4,
  42.     br150=5,
  43.     br200=6,
  44.     br300=7, 
  45.     br600=8,
  46.     br1200=9, 
  47.     br1800=10, 
  48.     br2400=11, 
  49.     br4800=12, 
  50.     br9600=13, 
  51.     br19200=14, 
  52.     br38400=15, 
  53. } baudRateType;
  54.  
  55. extern int microTimeStampA(struct timeval * oldTime);
  56.  
  57. #define            BR_MIN                 br50
  58. #define            BR_MIN_AUTO_CONF    br1200            
  59. #define            BR_MAX                 br38400
  60. #define         SCD_MAX_PACKETSIZE     (1024*8)    /* maximum packet size - some characters reserved to define pkt. */
  61. #define         SCD_RECV_BUFFERS    2
  62.  
  63. /*    error codes: */
  64. #define            SCD_TIMEOUT_ERR        (-1)        /* receive timeout expired. */
  65. #define            SCD_IO_ERR            (-2)        /* read/write/select failure. */
  66. #define            SCD_XFER_ERR        (-3)        /* not able to transfer packet. */ 
  67. #define            SCD_LENGTH_ERR        (-4)        /* Data too large for buffer. */
  68. #define            SCD_OPEN_ERR        (-5)        /* open/ioctl failed on tty port. */
  69.  
  70. @interface SerialCommDevice : Object
  71. {
  72.     int                fd;
  73.     int                xmitPktId;
  74.     int                dataPktLen;
  75.     int                dataPktIndex;
  76.     int                nackDPktFlag;
  77.     int                asciiRcvDPktID;
  78.     int                asciiAckDPktID;
  79.     int                maxXmitRetries;
  80.     int                recvTimeoutMsecs;
  81.     int                xmitAckTimeoutMsecs;
  82.     sccPortType        port;
  83.     baudRateType    baudRate;
  84.     char            *writeLock;        
  85.     char            *dataPktLock;
  86.     id                delegate;
  87.     char            recvBuf[SCD_RECV_BUFFERS][SCD_MAX_PACKETSIZE];
  88. }
  89.  
  90. - setRecvTimeoutMsecs:(int)msecs;
  91. - (int)recvTimeoutMsecs;
  92. - setXmitTimeoutMsecs:(int)msecs;
  93. - (int)xmitTimeoutMsecs;
  94. - setmaxXmitRetries:(int)retries;
  95. - (int)maxXmitRetries;
  96.  
  97. /*    xmit:,...
  98.  *
  99.  *    Send string to remote and wait for ack. Returns negative error code or
  100.  *    positive number of microseconds required for transfer.
  101.  */
  102. - (int)xmit:(char *)fmt, ...;
  103.  
  104.  
  105.  
  106. /*    xmit:len:
  107.  *
  108.  *    Send fixed-length binary character array to remote and wait for ack. Returns 
  109.  *    negative error code if failure, otherwise returns positive number of milliseconds 
  110.  *    required for transfer.
  111.  */
  112. - (int)xmit:(char *)buf len:(int)len;
  113.  
  114.  
  115.  
  116. /*    xmitOOL:,...
  117.  *
  118.  *    Send string to remote and wait for ack. Returns negative error code or
  119.  *    positive number of microseconds required for transfer.  If remote has
  120.  *    a delegate, the delegate is sent the data via the -oolMessage:len: msg.
  121.  *
  122.  */
  123. - (int)xmitOOL:(char *)fmt, ...;
  124.  
  125.  
  126.  
  127. /*    xmitOOL:len:
  128.  *
  129.  *    Send fixed-length binary character array to remote and wait for ack. Returns 
  130.  *    negative error code if failure, otherwise returns positive number of milliseconds 
  131.  *    required for transfer. If remote has a delegate, the delegate is sent the data 
  132.  *    via the -oolMessage:len: msg.
  133.  */
  134. - (int)xmitOOL:(char *)buf len:(int)len;
  135.  
  136.  
  137. /*    test:,...
  138.  *
  139.  *    Like xmit:,..., but sends a test packet instead of a data packet.  Test
  140.  *    packets are immediatly acknowledged by the remote's receiving thread and
  141.  *    are not forwarded to the receiving application.
  142.  *    Returns negative error code or positive number of microseconds 
  143.  *    required for transfer.
  144.  */
  145. - (int)test:(char *)fmt, ...;
  146.  
  147.  
  148.  
  149. /*    test:len:
  150.  *
  151.  *    Like xmit:len:, but sends a test packet instead of a data packet.  Test
  152.  *    packets are immediatly acknowledged by the remote's receiving thread (if
  153.  *    it is up and running), and the packet is not forwarded to the receiving 
  154.  *    application.   Returns negative error code or positive number of 
  155.  *    microseconds required for transfer.
  156.  */
  157. - (int)test:(char *)buf len:(int)len;
  158.  
  159.  
  160. /*    -initPort:
  161.  *    Open specified port and walk thru baud rates until one is
  162.  *    found where remote acknoledges xfer (via -test:).  If no
  163.  *    acks are ever generated, then a default(38.4Kbaud) is selected.
  164.  */
  165. - initPort:(sccPortType)thePort ;
  166.  
  167.  
  168. /*    pollRecvBufferReady
  169.  *
  170.  *    Returns 1 if recv Buffer contains data and is ready to be read, otherwise returns 0.
  171.  */
  172. - (int)pollRecvBufferReady;
  173.  
  174. /*    recv:maxLen:
  175.  *
  176.  *    Returns negative error code if failure, otherwise returns positive 
  177.  *    number of characters received.
  178.  */
  179. - (int)recv:(char *)str maxLen:(int)len;
  180.  
  181.  
  182.  
  183. /*    - setPort:atRate:
  184.  *
  185.  *    Change port and/or transmission parameters.
  186.  *    Return 0 on success and non-zero if fail.
  187.  */
  188. - (int)setPort:(sccPortType)thePort atRate:(baudRateType)theRate;
  189.  
  190.  
  191.  
  192.  
  193. /*    - initPort:atRate:
  194.  *
  195.  *    open specified port at specified rate. Returns nil on failure.
  196.  */
  197. - initPort:(sccPortType)thePort atRate:(baudRateType)theRate;
  198.  
  199.  
  200. /*    - initPort:
  201.  *
  202.  *    open specified port and search for match baud rate. Returns nil on failure.
  203.  */
  204. - initPort:(sccPortType)thePort;
  205.  
  206.  
  207. /*    - init
  208.  *
  209.  *    open default port (A) and search for match baud rate. Returns nil on failure.
  210.  */
  211. - init;
  212.  
  213. -setDelegate:myDelegate;
  214. -delegate;
  215. @end
  216.  
  217. @interface SCDDelegate : Object
  218. {}
  219. /*    - oolMessage:len:
  220.  *
  221.  *    An asyncronous message that can be generated by this object at any time.  Comes in the 
  222.  *    context of the background thread that is normally used to read data off the serial port 
  223.  *    (therefore can not be used to draw or to call any of this object's -xmit or  -recv
  224.  *    methods).  Note that the delegate's method should return reasonably quickly in order 
  225.  *    for the thread to continue to receive new data.  WARNING: The contents of bufr can 
  226.  *    change as soon as this method returns.
  227.  */
  228. -oolMessage:(char *)bufr len:(int)l;
  229. @end
  230.